(And if you have created some nice things, think about sharing them, too!)
This is a Plugin for REALbasic version 2 or later (it does not work with REALbasic v1!). Plugins contain usually low-level code that cannot be written using the REALbasic language directly.
The plugin and the sample RB program were created and tested using CodeWarrior Pro 3 and REALbasic 2.0.2.
More REALbasic examples can be found on my Web Site at
<http://www.tempel.org/rb/>
Enjoy!
Overview
This Plugin extends the functionality of the RB-internal class MemoryBlock.
The addition you will most likely appreciate is that you can now copy Strings and Double (64 bit floating point) values from and to a MemoryBlock. Without this plugin, only simple data types, like Integers, could be accessed in a MemoryBlock.
There's also a function to inquire the Size of the MemoryBlock, and some powerful functions to copy big chunks of memory around in MemoryBlocks and even to and from Mac's main memory.
Installation
1. Quit REALbasic if it is running
2. Place the file TT's MemoryBlock-Plugin into a folder called Plugins, which resides in the same folder where your REALbasic application is.
3. Now you can launch REALbasic again. The methods, controls or classes described below will be available to your RB applications and to the RB demo project that came with this plugin.
MemoryBlock Properties & Methods added by this Plugin
Note: If you do not understand certain functions provided here, look into the enclosed demo projects for examples.
• Size as Integer
Returns the size of the MemoryBlock (it is the same size value that was specified when creating the object calling the function NewMemoryBlock). If this value is zero, then the MemoryBlock was not allocated by NewMemoryBlock, but rather retrieved from a Shared Lib call.
• DoubleValue(offset as Integer) as Double
Similar to the other properties, like SingleValue, or Long, this one allows you to access 64 Bit (8 Byte) IEEE floating point numbers in a MemoryBlock.
• GetString(offset as Integer, numBytes as Integer) as String
Copies the specified amount of bytes from the MemoryBlock and returns them as a String object.
• SetString(str as String, offset as Integer)
Overwrites the contents of the MemoryBlock with the provided string. Contents of the MemoryBlock outside of the string's dimension remain unchanged.
Note: You must make sure that the copied bytes fit inside the block (if they don't, your application or even the whole system can crash).
• CopyBytes(srcOfs as Integer, numBytes as Integer, destOfs as Integer)
Copies the specified amount of bytes inside the MemoryBlock.
Note: You must make sure that the copied bytes fit inside the block (if they don't, your application or even the whole system can crash).
• CopyBytes(srcOfs as Integer, numBytes as Integer, destBlk as MemoryBlock, destOfs as Integer)
Copies the specified amount of bytes into a second MemoryBlock.
Note: You must make sure that the destination block is large enough to hold the copied bytes (if not, your application or even the whole system can crash).
• CopyBytesToMacPtr(srcOfs as Integer, numBytes as Integer, destPtr as Integer)
Copies the given amount of bytes from the MemoryBlock to the given address in the Mac's memory address space.
Note: Be careful where you copy the data to - you can easily crash your computer if you write to the wrong address space.
• CopyBytesFromMacPtr(srcPtr as Integer, numBytes as Integer, destOfs as Integer)
Copies the given amount of bytes from the given address in the Mac's memory address space into the MemoryBlock.
Note: Make sure that the destination block is large enough to hold the copied bytes (if not, your application or even the whole system can crash).
• CopyBytesToMacHandle(srcOfs as Integer, numBytes as Integer, destPtr as Integer)
• CopyBytesFromMacHandle(srcPtr as Integer, numBytes as Integer, destOfs as Integer)
Same as CopyBytesToMacPtr and CopyBytesFromMacPtr, only that the memory address is a so-called Handle (see documentation about the MacOS Memory Manager), which is double-referenced.
Plugin Programming Information
The plugin code is a Metrowerks CodeWarrior Pro 3 (IDE 3.1) project.
If you have an older CW version that refuses to open the prj file, then create a new and set/enable the following prj options:
• create 68K target (set to 68K linker)
• prj type: Code Resource, File Name "CatalogSearch-Plugin", Creator "SfTg", Type "RBPl", ResType "PL68", ResID "128", Extended Resource, Header Type "Standard"
• C/C++ language settings: Prefix File "MacHeaders.h"
• 68K Processor: 68020 Codegen, Code Model "Smart", Struct Alignm. "PowerPC", 4-Byte Ints, 8-Byte Doubles, MPW C Call. Conv.
• 68K Linker: Link Single Segment, Merge Compiler Glue…, Dead-strip Static Init Code
• Add the files "Plugin Source.cpp", "PluginMain.cpp", "MacOS.lib", "Version Info.rsrc" and a 68K C lib with (4i_8d) in its name to the project.
To compile the project, you also need to have the "Plugin SDK" available, which you can download from RB's website.
